home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / linux.68k / docs / dd-dri~1.z / dd-dri~1
Text File  |  1993-04-12  |  33KB  |  948 lines
  1. ************************************************************
  2. *                                                          *
  3. *    Guide To Linux Driver Writing -- Character Devices    *
  4. *                                                          *
  5. *                            or,                           *
  6. *                                                          *
  7. *         The Wacky World of Driver Development (I)        *
  8. *                                                          *
  9. *                 Last Revision: Apr 11, 1993              *
  10. *                                                          *
  11. ************************************************************
  12.  
  13. This document (C) 1993 Robert Baruch.  This document may be freely 
  14. copied as long as the entire title, copyright, this notice, and all of
  15. the introduction are included along with it.  Suggestions, criticisms,
  16. and comments to baruch@nynexst.com.  This document, nor the work
  17. performed by Robert Baruch using Linux, nor the results of said work
  18. are connected in any way to any of the Nynex companies.  Information
  19. may settle during transportation.  This product should not be used
  20. in conjunction with a dietary regime except under supervision by your
  21. doctor.
  22.  
  23. Right, now that that's over with, let's get into the fun stuff!
  24.  
  25. ========================
  26.      Introduction
  27. ========================
  28.  
  29. There is a companion guide to this Guide, the Linux Character Device
  30. Tutorial.  This tutorial contains working examples of driver code.  It
  31. introduces the reader gently into each aspect of character device driver
  32. writing through experiments which are carried out by the programmer.
  33.  
  34. This Guide should serve as a reference to both beginning and advanced
  35. driver writers.
  36.  
  37. -=-=-=-=-=-=-
  38.  
  39. Some words of thanks:
  40.  
  41. Many thanks to:
  42.  
  43.  Donald J. Becker (becker@metropolis.super.org)
  44.  Don Holzworth (donh@gcx1.ssd.csd.harris.com)
  45.  Michael Johnson (johnsonm@stolaf.edu)
  46.  Karl Heinz Kremer (khk@raster.kodak.com)
  47.  All the driver writers!
  48.  
  49. ...and of course, Linus "Linux" Torvalds and all the guys who helped
  50.  develop Linux into a BLOODY KICKIN' O/S!
  51.  
  52. -=-=-=-=-=-=-
  53.  
  54. ...and now a word of warning:
  55.  
  56. Messing about with drivers is messing with the kernel.  Drivers are run
  57. at the kernel level, and as such are not subject to scheduling.  Further,
  58. drivers have access to various kernel structures.  Before you actually
  59. write a driver, be *damned* sure of what you are doing, lest you end
  60. up having to re-format your harddrive and re-install Linux!
  61.  
  62. The information in this Guide is as up-to-date as I could make it.  It also
  63. has no stamp of approval whatsoever by any of the designers of the kernel.
  64. I am not responsible for damage caused to anything as a result of using this
  65. Guide.
  66.  
  67. ========================
  68.   End of Introduction
  69. ========================
  70.  
  71. Kernal-callable functions:
  72. --------------------------
  73.  
  74. Note:  There is no close for a character device.  There is only release.
  75. See the file data structure below to find out how to determine the number
  76. of processes which have the device open.
  77.  
  78. -=-=-=-=-=-=-=-
  79.  
  80. init : Initializes the driver on bootup.
  81.  
  82.   unsigned long driver_init(unsigned long kmem_start, unsigned long kmem_end)
  83.  
  84. Arguments: kmem_start -- the start of kernel memory
  85.            kmem_end   -- the end of kernel memory
  86.  
  87. Returns: The new start of kernel memory.  This will be different from the
  88.   kmem_start argument if you want to allocate memory for the driver.
  89.  
  90. The arguments you use depends on what you want to do.  Remember that since
  91. you are going to add your init function to kernel/chr_dev/mem.c, you can
  92. make your call anything you like, but you have access to the kernel memory
  93. start and end.
  94.  
  95. Generally, the init function initializes the driver and hardware, and
  96. displays some message telling of the availability of the driver and
  97. hardware.  In addition, the register_chrdev function is usually called here.
  98.  
  99.  
  100. **************
  101. open : Open a device
  102.  
  103.   static int driver_open(struct inode * inode, struct file * file)
  104.  
  105. Arguments: inode    -- pointer to the inode structure for this device
  106.            file     -- pointer to the file structure for this device
  107.  
  108. Returns: 0 on success,
  109.          -errno on error.
  110.  
  111. This function is called whenever a process performs open (or fopen) on
  112. the device special file.  If there is no open function for the driver,
  113. nothing spectacular happens.  As long as the /dev file exists, the
  114. open will succeed.
  115.  
  116.  
  117. **************
  118. read : Read from a device
  119.  
  120.   static int driver_read(struct inode * inode, struct file * file, 
  121.                          char * buffer, int count)
  122.  
  123. Arguments: inode    -- pointer to the inode structure for this device
  124.            file     -- pointer to the file structure for this device
  125.            buffer   -- pointer to the buffer in user space to read into
  126.            count    -- the number of bytes to read
  127.  
  128. Returns: -errno on error
  129.          >=0 : the number of bytes actually read
  130.  
  131. If there is no read function for the driver, read calls will return EINVAL.
  132.  
  133.  
  134. **************
  135. write : Write to a device
  136.  
  137.   static int driver_write(struct inode * inode, struct file * file, 
  138.                           char * buffer, int count)
  139.  
  140. Arguments: inode    -- pointer to the inode structure for this device
  141.            file     -- pointer to the file structure for this device
  142.            buffer   -- pointer to the buffer in user space to write from
  143.            count    -- the number of bytes to write
  144.  
  145. Returns: -errno on error
  146.          >=0 : the number of bytes actually written
  147.  
  148. If there is no write function for the driver, write calls will return
  149. EINVAL.
  150.  
  151.  
  152. **************
  153. lseek : Change the position offset of the device
  154.  
  155.   static int driver_lseek(struct inode * inode, struct file * file,
  156.                           off_t offset, int origin)
  157.  
  158. Arguments: inode    -- pointer to the inode structure for this device
  159.            file     -- pointer to the file structure for this device
  160.            offset   -- offset from origin to move to (bytes)
  161.            origin   -- origin to move from :
  162.                        0 = from origin 0 (beginning)
  163.                        1 = from current position
  164.                        2 = from end
  165.  
  166. Returns: -errno on error
  167.          >=0 : the position after the move
  168.  
  169. See Also: Data Structure 'file'
  170.  
  171. If there is no lseek function for the driver, the kernel will take the default
  172. seek action, which is to alter the file->f_pos element.  For origins of 2,
  173. the default action results in -EINVAL if file->f_inode is NULL, or it
  174. sets file->f_pos to file->f_inode->i_size + offset otherwise.
  175.  
  176.  
  177. **************
  178. ioctl : Various device-dependent services
  179.  
  180.   static int driver_ioctl(struct inode *inode, struct file *file,
  181.                           unsigned int cmd, unsigned long arg)
  182.  
  183. Arguments: inode    -- pointer to the inode structure for this device
  184.            file     -- pointer to the file structure for this device
  185.            cmd      -- the user-defined command to perform
  186.            arg      -- the user-defined argument.  You may use this
  187.                        as a pointer to user space, since sizeof(long)==
  188.                        sizeof(void *).
  189.  
  190. Returns: -errno on error
  191.          >=0 : whatever you like! (user-defined)
  192.  
  193. For cmd, FIOCLEX, FIONCLEX, FIONBIO, and FIOASYNC are already defined.
  194. See the file linux/fs/ioctl.c, sys_ioctl to find out what they do.
  195. If there is no ioctl call for the driver, and the ioctl command performed
  196. is not one of the four types listed here, ioctl will return -EINVAL.
  197.  
  198.  
  199. **************
  200. select : Performs the select call on the device:
  201.  
  202.   static int driver_select(struct inode *inode, struct file *file, 
  203.                            int sel_type, select_table * wait)
  204.  
  205. Arguments: inode    -- pointer to the inode structure for this device
  206.            file     -- pointer to the file structure for this device
  207.            sel_type -- the select type to perform :
  208.                         SEL_IN (read)
  209.                         SEL_OUT (write)
  210.                         SEL_EX (exception)
  211.            wait     -- see the section "Some Notes" for select.
  212.  
  213. Returns: 0 if the device is not ready to perform the sel_type operation
  214.          !=0 if it is.
  215.  
  216. See the "Some Notes" section 'way below on information on h